|
|
ChangedResource |
||||
| Header: | Resources.h | Carbon status: | Supported | |
Sets a flag in the resource’s resource map entry in memory to show that you’ve made changes to a resource’s data or to an entry in a resource map.
void ChangedResource (
Handle theResource
);
A handle to the resource whose data you’ve changed. The function sets the resChanged attribute for that resource in the resource map in memory. If the resChanged attribute for a resource has been set and your application calls the UpdateResFile function or quits, the Resource Manager writes the resource data for that resource (and for all other resources whose resChanged attribute is set) and the entire resource map to the resource fork of the corresponding file on disk. If the resChanged attribute for a resource has been set and your application calls the WriteResource function, the Resource Manager writes only the resource data for that resource to disk.
If the given handle isn’t a handle to a resource, if the modified resource data can’t be written to the resource fork, or if the resProtected attribute is set for the modified resource, the function does nothing. To find out whether any of these errors occurred, call the ResError function.
If you change information in the resource map with a call to the SetResInfo or SetResAttrs function and then call ChangedResource and UpdateResFile, the Resource Manager still writes both the resource map and the resource data to disk. If you want any of your changes to the resource map or resource data to be temporary, you must restore the original information before the Resource Manager updates the resource fork on disk.
After writing a resource to disk, the Resource Manager clears the resource’s resChanged attribute in the appropriate entry of the resource map in memory.
When your application calls this function, the Resource Manager attempts to reserve enough disk space to contain the changed resource. The function reserves space every time you call it, but the resource is not actually written until you call WriteResource or UpdateResFile. Thus, if you call ChangedResource several times before the resource is actually written, the function reserves much more space than is needed. If the resource is large, you may unexpectedly run out of disk space. When the resource is actually written, the file’s end-of-file (EOF) is set correctly, and the next call to ChangedResource will work as expected.
If the modified resource data can’t be written to the resource fork (for example, if there’s not enough room on disk), the resChanged attribute is not set to 1. If this is the case and you call UpdateResFile or WriteResource, the Resource Manager won’t know that the resource data has been changed. Thus, the function won’t write the modified resource data to the resource fork and won’t return an error. For this reason, always make sure that the ResError function returns the result code noErr after a call to ChangedResource.
If your application frequently changes the contents of resources (especially large resources), you should call WriteResource or UpdateResFile immediately after calling ChangedResource.
If you need to make changes to a purgeable resource using functions that may cause the Memory Manager to purge the resource, you should make the resource temporarily not purgeable. To do so, use the Memory Manager functions HGetState, HNoPurge, and HSetState to make sure the resource data remains in memory while you change it and until the resource data is written to disk. (You can’t use the SetResAttrs function for this purpose, because the changes don’t take effect immediately.) First call HGetState and HNoPurge, then change the resource as necessary. To make a change to a resource permanent, use ChangedResource and UpdateResFile or WriteResource; then call HSetState when you’re finished. Or, instead of calling WriteResource to write the resource data immediately, you can call the SetResPurge function with the install parameter set to TRUE before making changes to purgeable resource data.
If your application doesn’t make its resources purgeable, or if the changes you are making to a purgeable resource don’t involve functions that may cause the resource to be purged, you don’t need to take these precautions
This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.
© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)